home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / 3DBorder.3 next >
Text File  |  1994-09-20  |  15KB  |  331 lines
  1.  
  2.  
  3.  
  4. Tk_Get3DBorder(3)     Tk Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tk_Get3DBorder,   Tk_Draw3DRectangle,    Tk_Fill3DRectangle,
  12.      Tk_Draw3DPolygon,                          Tk_Fill3DPolygon,
  13.      Tk_SetBackgroundFromBorder,               Tk_NameOf3DBorder,
  14.      Tk_Free3DBorder   -   draw  borders  with  three-dimensional
  15.      appearance
  16.  
  17. SYNOPSIS
  18.      #include <tk.h>
  19.  
  20.      Tk_3DBorder
  21.      Tk_Get3DBorder(_i_n_t_e_r_p, _t_k_w_i_n, _c_o_l_o_r_M_a_p, _c_o_l_o_r_N_a_m_e)
  22.  
  23.      void
  24.      Tk_Draw3DRectangle(_d_i_s_p_l_a_y, _d_r_a_w_a_b_l_e, _b_o_r_d_e_r, _x, _y, _w_i_d_t_h, _h_e_i_g_h_t, _b_o_r_d_e_r_W_i_d_t_h, _r_e_l_i_e_f)
  25.  
  26.      void
  27.      Tk_Fill3DRectangle(_d_i_s_p_l_a_y, _d_r_a_w_a_b_l_e, _b_o_r_d_e_r, _x, _y, _w_i_d_t_h, _h_e_i_g_h_t, _b_o_r_d_e_r_W_i_d_t_h, _r_e_l_i_e_f)
  28.  
  29.      void
  30.      Tk_Draw3DPolygon(_d_i_s_p_l_a_y, _d_r_a_w_a_b_l_e, _b_o_r_d_e_r, _p_o_i_n_t_P_t_r, _n_u_m_P_o_i_n_t_s, _p_o_l_y_B_o_r_d_e_r_W_i_d_t_h, _l_e_f_t_R_e_l_i_e_f)
  31.  
  32.      void
  33.      Tk_Fill3DPolygon(_d_i_s_p_l_a_y, _d_r_a_w_a_b_l_e, _b_o_r_d_e_r, _p_o_i_n_t_P_t_r, _n_u_m_P_o_i_n_t_s, _p_o_l_y_B_o_r_d_e_r_W_i_d_t_h, _l_e_f_t_R_e_l_i_e_f)
  34.  
  35.      void
  36.      Tk_SetBackgroundFromBorder(_t_k_w_i_n, _b_o_r_d_e_r)
  37.  
  38.      char *
  39.      Tk_NameOf3DBorder(_b_o_r_d_e_r)
  40.  
  41.      XColor *                                                      |
  42.      Tk_3DBorderColor(_b_o_r_d_e_r)                                      |
  43.  
  44.      Tk_Free3DBorder(_b_o_r_d_e_r)
  45.  
  46. ARGUMENTS
  47.      Tcl_Interp    *_i_n_t_e_r_p       (in)      Interpreter to use for
  48.                                            error reporting.
  49.  
  50.      Tk_Window     _t_k_w_i_n         (in)      Token  for  window  in
  51.                                            which  border  will be
  52.                                            drawn.
  53.  
  54.      Colormap      _c_o_l_o_r_m_a_p      (in)      Colormap from which to
  55.                                            allocate  colors.   If
  56.                                            None, then the default
  57.                                            colormap  for  _t_k_w_i_n's
  58.                                            screen is used.
  59.  
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tk_Get3DBorder(3)     Tk Library Procedures
  71.  
  72.  
  73.  
  74.      Tk_Uid        _c_o_l_o_r_N_a_m_e     (in)      Textual description of
  75.                                            color corresponding to
  76.                                            background       (flat
  77.                                            areas).    Illuminated
  78.                                            edges will be brighter
  79.                                            than  this,  and  sha-
  80.                                            dowed  edges  will  be
  81.                                            darker than this.
  82.  
  83.      Display       *_d_i_s_p_l_a_y      (in)      Xlib pointer  indicat-
  84.                                            ing display with which
  85.                                            drawable  is   associ-
  86.                                            ated.
  87.  
  88.      Drawable      _d_r_a_w_a_b_l_e      (in)      X token for window  or
  89.                                            pixmap;      indicates
  90.                                            where border is to  be
  91.                                            drawn.
  92.  
  93.      Tk_3DBorder   _b_o_r_d_e_r        (in)      Token for border  pre-
  94.                                            viously  allocated  in
  95.                                            call                to
  96.                                            Tk_Get3DBorder.
  97.  
  98.      int           _x             (in)      X-coordinate        of
  99.                                            upper-left  corner  of
  100.                                            rectangle   describing
  101.                                            border.
  102.  
  103.      int           _y             (in)      Y-coordinate        of
  104.                                            upper-left  corner  of
  105.                                            rectangle   describing
  106.                                            border.
  107.  
  108.      int           _w_i_d_t_h         (in)      Width   of   rectangle
  109.                                            describing  border, in
  110.                                            pixels.
  111.  
  112.      int           _h_e_i_g_h_t        (in)      Height  of   rectangle
  113.                                            describing  border, in
  114.                                            pixels.
  115.  
  116.      int           _b_o_r_d_e_r_W_i_d_t_h   (in)      Width  of  border   in
  117.                                            pixels. Positive means
  118.                                            border is inside  rec-
  119.                                            tangle  given by _x, _y,
  120.                                            _w_i_d_t_h,  _h_e_i_g_h_t,  nega-
  121.                                            tive  means  border is
  122.                                            outside rectangle.
  123.  
  124.      int           _r_e_l_i_e_f        (in)      Indicates 3-D position
  125.                                            of     interior     of
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tk_Get3DBorder(3)     Tk Library Procedures
  137.  
  138.  
  139.  
  140.                                            rectangle relative  to
  141.                                            exterior;   should  be
  142.                                            TK_RELIEF_RAISED,
  143.                                            TK_RELIEF_SUNKEN,
  144.                                            TK_RELIEF_GROOVE,   or  |
  145.                                            TK_RELIEF_RIDGE   (may  |
  146.                                            also be TK_RELIEF_FLAT
  147.                                            for
  148.                                            Tk_Fill3DRectangle).
  149.  
  150.      XPoint        *_p_o_i_n_t_P_t_r     (in)      Pointer  to  array  of
  151.                                            points  describing the
  152.                                            set of vertices  in  a
  153.                                            polygon.   The polygon
  154.                                            need not be closed (it
  155.                                            will     be     closed
  156.                                            automatically  if   it
  157.                                            isn't).
  158.  
  159.      int           _n_u_m_P_o_i_n_t_s     (in)      Number  of  points  at
  160.                                            *_p_o_i_n_t_P_t_r.
  161.  
  162.      int           _p_o_l_y_B_o_r_d_e_r_W_i_d_t_h(in)     Width  of  border   in
  163.                                            pixels.   If positive,
  164.                                            border  is  drawn   to
  165.                                            left   of   trajectory
  166.                                            given by _p_o_i_n_t_P_t_r;  if
  167.                                            negative,   border  is
  168.                                            drawn to right of tra-
  169.                                            jectory.   If  _l_e_f_t_R_e_-
  170.                                            _l_i_e_f                is
  171.                                            TK_RELIEF_GROOVE    or
  172.                                            TK_RELIEF_RIDGE   then
  173.                                            the border is centered
  174.                                            on the trajectory.
  175.  
  176.      int           _l_e_f_t_R_e_l_i_e_f    (in)      Height of left side of
  177.                                            polygon's  path  rela-
  178.                                            tive     to     right.
  179.                                            TK_RELIEF_RAISED means
  180.                                            left    side    should
  181.                                            appear    higher   and
  182.                                            TK_RELIEF_SUNKEN means
  183.                                            right    side   should
  184.                                            appear         higher;  |
  185.                                            TK_RELIEF_GROOVE   and  |
  186.                                            TK_RELIEF_RIDGE   mean  |
  187.                                            the   obvious  things.
  188.                                            For  Tk_Fill3DPolygon,
  189.                                            TK_RELIEF_FLAT     may
  190.                                            also be  specified  to
  191.                                            indicate no difference
  192.  
  193.  
  194.  
  195. Tk                                                              3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. Tk_Get3DBorder(3)     Tk Library Procedures
  203.  
  204.  
  205.  
  206.                                            in height.
  207. _________________________________________________________________
  208.  
  209.  
  210. DESCRIPTION
  211.      These procedures provide facilities for drawing window bord-
  212.      ers  in  a way that produces a three-dimensional appearance.
  213.      Tk_Get3DBorder allocates colors and Pixmaps needed to draw a
  214.      border  in  the  window  given  by  the _t_k_w_i_n argument.  The
  215.      _c_o_l_o_r_m_a_p argument specifies a Colormap to use for allocating
  216.      colors,  and  the  _c_o_l_o_r_N_a_m_e  argument indicates what colors
  217.      should be used in the border.  _C_o_l_o_r_N_a_m_e may  be  any  value
  218.      acceptable to Tk_GetColor.  The color indicated by _c_o_l_o_r_N_a_m_e
  219.      will not actually be used in the border;  it  indicates  the
  220.      background  color for the window (i.e. a color for flat sur-
  221.      faces).  The illuminated portions of the border will  appear
  222.      brighter  than indicated by _c_o_l_o_r_N_a_m_e, and the shadowed por-
  223.      tions of the border will appear darker than _c_o_l_o_r_N_a_m_e.
  224.  
  225.      Tk_Get3DBorder returns a token that may  be  used  in  later
  226.      calls to Tk_Draw3DRectangle.  If an error occurs in allocat-
  227.      ing information for the border (e.g. _c_o_l_o_r_N_a_m_e isn't a legal
  228.      color specifier), then NULL is returned and an error message
  229.      is left in _i_n_t_e_r_p->_r_e_s_u_l_t.
  230.  
  231.      Once a border structure has been created, Tk_Draw3DRectangle
  232.      may be invoked to draw the border.  The _d_i_s_p_l_a_y and _d_r_a_w_a_b_l_e
  233.      arguments specify a window or pixmap in which the border  is
  234.      to  be drawn.  _D_r_a_w_a_b_l_e need not refer to the same window as
  235.      the _t_k_w_i_n used to create the border, but it must refer to  a
  236.      compatible  pixmap  or window:  one associated with the same
  237.      display and with the same depth as the _t_k_w_i_n used to  create
  238.      the  border.   The  _x, _y, _w_i_d_t_h, and _h_e_i_g_h_t arguments define
  239.      the bounding box of the border region within _d_r_a_w_a_b_l_e  (usu-
  240.      ally  _x  and  _y are zero and _w_i_d_t_h and _h_e_i_g_h_t are the dimen-
  241.      sions of the window), and _b_o_r_d_e_r_W_i_d_t_h specifies  the  number
  242.      of pixels actually occupied by the border.  The _r_e_l_i_e_f argu-
  243.      ment indicates which of several three-dimensional effects is
  244.      desired:  TK_RELIEF_RAISED  means  that  the interior of the
  245.      rectangle should appear raised relative to the  exterior  of
  246.      the  rectangle, and TK_RELIEF_SUNKEN means that the interior
  247.      should    appear    depressed.      TK_RELIEF_GROOVE     and  |
  248.      TK_RELIEF_RIDGE mean that there should appear to be a groove  |
  249.      or ridge around the exterior of the rectangle.
  250.  
  251.      Tk_Fill3DRectangle  is  somewhat   like   Tk_Draw3DRectangle
  252.      except  that  it  first  fills the rectangular area with the
  253.      background color (one corresponding to the _c_o_l_o_r_N_a_m_e used to
  254.      create  _b_o_r_d_e_r).  Then it calls Tk_Draw3DRectangle to draw a
  255.      border just inside the outer edge of the  rectangular  area.
  256.      The   argument   _r_e_l_i_e_f   indicates   the   desired   effect
  257.      (TK_RELIEF_FLAT means no border should be  drawn;  all  that
  258.  
  259.  
  260.  
  261. Tk                                                              4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. Tk_Get3DBorder(3)     Tk Library Procedures
  269.  
  270.  
  271.  
  272.      happens is to fill the rectangle with the background color).
  273.  
  274.      The procedure Tk_Draw3DPolygon may be used to draw more com-
  275.      plex   shapes  with  a  three-dimensional  appearance.   The
  276.      _p_o_i_n_t_P_t_r  and  _n_u_m_P_o_i_n_t_s  arguments  define  a   trajectory,
  277.      _p_o_l_y_B_o_r_d_e_r_W_i_d_t_h indicates how wide the border should be (and
  278.      on which side of the trajectory to draw it), and  _l_e_f_t_R_e_l_i_e_f
  279.      indicates which side of the trajectory should appear raised.
  280.      Tk_Draw3DPolygon draws a border around the given  trajectory
  281.      using  the colors from _b_o_r_d_e_r to produce a three-dimensional
  282.      appearance.  If the trajectory is non-self-intersecting, the
  283.      appearance  will  be  a raised or sunken polygon shape.  The
  284.      trajectory may be self-intersecting, although it's not clear
  285.      how useful this is.
  286.  
  287.      Tk_Fill3DPolygon     is     to     Tk_Draw3DPolygon     what
  288.      Tk_Fill3DRectangle  is  to Tk_Draw3DRectangle:  it fills the
  289.      polygonal area with the background color from  _b_o_r_d_e_r,  then
  290.      calls  Tk_Draw3DPolygon  to  draw  a  border around the area
  291.      (unless _l_e_f_t_R_e_l_i_e_f  is  TK_RELIEF_FLAT;   in  this  case  no
  292.      border is drawn).
  293.  
  294.      The procedure  Tk_SetBackgroundFromBorder  will  modify  the
  295.      background  pixel and/or pixmap of _t_k_w_i_n to produce a result
  296.      compatible with _b_o_r_d_e_r.  For color displays,  the  resulting
  297.      background  will  just  be  the color given by the _c_o_l_o_r_N_a_m_e
  298.      argument passed to Tk_Get3DBorder when _b_o_r_d_e_r  was  created;
  299.      for  monochrome displays, the resulting background will be a
  300.      light stipple pattern, in order  to  distinguish  the  back-
  301.      ground from the illuminated portion of the border.
  302.  
  303.      Given a token for a border, the procedure  Tk_NameOf3DBorder
  304.      will   return  the  _c_o_l_o_r_N_a_m_e  string  that  was  passed  to
  305.      Tk_Get3DBorder to create the border.
  306.  
  307.      The procedure Tk_3DBorderColor returns the XColor  structure  |
  308.      that  will  be  used  for flat surfaces drawn for its _b_o_r_d_e_r  |
  309.      argument by procedures like Tk_Fill3DRectangle.  The  return  |
  310.      value corresponds to the _c_o_l_o_r_N_a_m_e passed to Tk_Get3DBorder.  |
  311.      The XColor, and its  associated  pixel  value,  will  remain  |
  312.      allocated as long as _b_o_r_d_e_r exists.
  313.  
  314.      When a border is no longer needed, Tk_Free3DBorder should be
  315.      called  to release the resources associated with the border.
  316.      There should be exactly one call to Tk_Free3DBorder for each
  317.      call to Tk_Get3DBorder.
  318.  
  319.  
  320. KEYWORDS
  321.      3D,  background,  border,  color,  depressed,  illumination,
  322.      polygon, raised, shadow, three-dimensional effect
  323.  
  324.  
  325.  
  326.  
  327. Tk                                                              5
  328.  
  329.  
  330.  
  331.